package org.lightcommons.orm;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

/**
 * @author gl
 * 
 * @since 2007-10-12
 */
public interface DaoTemplate {
	/**
	 * 使用session.get(id)从数据库中取得一个实体
	 * 
	 * @param id
	 *            期望的实体id
	 * @return 期望的实体，不存在返回null
	 * @see #load(Serializable)
	 */
	<T> T get(Class<T> entityClass,final Serializable id);
	
	/**
	 * 保存新实体，相当于sql中的insert into
	 * 
	 * @param entity
	 *            要保存的实体
	 * @return 保存后的实体id
	 * @see #update(HasId)
	 * @see #saveOrUpdate(HasId)
	 */
	Serializable save(final Object entity);

	/**
	 * 更新已存在的实体，相当于sql中的update
	 * 
	 * @param entity
	 *            要更新的实体
	 * @see #save(HasId)
	 * @see #saveOrUpdate(HasId)
	 */
	void update(final Object entity);

	/**
	 * 保存或更新
	 * 
	 * @param entity
	 *            要保存或更新的实体
	 * @see #save(HasId)
	 * @see #update(HasId)
	 */
	void saveOrUpdate(final Object entity);

	/**
	 * 删除实体
	 * 
	 * @param entity
	 *            要删除的实体
	 */
	<T> T delete(final T entity);

	/**
	 * 根据实体id删除实体
	 * 
	 * @param id
	 *            要删除的实体的id
	 * 
	 */
	<T> T deleteById(Class<T> entityClass,final Serializable id);

	/**
	 * 列出所有实体
	 * 
	 * @return 所有实体
	 * 
	 */
	<T> List<T> findAll(Class<T> entityClass);

	/**
	 * 
	 * 根据example对象查找匹配的对象
	 * <p>
	 * 如：要查询FirstName象four，LastName象lee的员工<br>
	 * <code>
	 * GenericDao<Employee,Long> dao;<br>
	 * ...init the dao<br>
	 * Employee example = new Employee();<br>
	 * example.setFirstName("four");<br>
	 * example.setLastName("lee");<br>
	 * List result = dao.findByExample(example);<br>
	 * </code> 这样Four Lee,Four2 Lee2,xxFour xxLeexx,都将满足查询条件
	 * 
	 * @param exampleEntity
	 *            作为查询条件的对象
	 * @return 与exampleEntity相符合的对象，忽略exampleEntity的null字段，exampleEntity中所有字符串字段使用like操作且忽略大小写
	 * 
	 * @see #getPageByExample(HasId, int)
	 */
	<T>List<T> findByExample(final T exampleEntity);

	<T>List<T> findByQuery(String query,Object... values);
	
	<T>List<T> findByNamedQuery(String namedQuery,Map<String,Object> values);
	
	<T>List<T> findByKeyWord(Class<T> entityClass,String inculdKeywords,String excludeKeywords);

	
	/**
	 * 获取分页对象
	 * 
	 * @param maxResults
	 *            每页显示的最大条目
	 * @return 分页对象
	 * @see Page
	 */
	<T> Page<T> getPage(final Class<T> entityClass,final int pageIndex,final int maxResults);
	/**
	 * 根据exampleEntity获取查询结果，并转换为分页对象
	 * 
	 * @param exampleEntity
	 *            the entity to query
	 * @param maxResults
	 *            每页显示的最大条目
	 * @return 分页对象
	 * @see #findByExample(HasId)
	 * @see Page
	 */
	<T>Page<T> getPageByExample(final T exampleEntity,final int pageIndex, final int maxResults);

	<T>Page<T> getPageByQuery(String query,int pageIndex,int maxResults,Object... values);
	
	<T>Page<T> getPageByNamedQuery(String namedQuery,int pageIndex,int maxResults,Map<String,Object> values);
	
	<T>Page<T> getPageByKeyWord(Class<T> entityClass,String inculdKeywords,String excludeKeywords,int pageIndex,int maxResults);


}
